QuickTime 4 Reference

Special Description Types

If the parameter atom type and ID atom of a parameter description contains the constant kNoAtom , this indicates that the value being described is not a parameter to the effect but is a group. Besides groups, two further special cases are covered in the following sections-- enumeration lists and source counts.

Groups

It is sometimes useful to treat a set of parameters as a group. For example, you might want to label a group of parameters that jointly control something, align a group of controls, or enclose a set of parameters in a box. The grouping mechanism allows you to specify a set of parameters and the attributes that are applied to the group.

If the parameter data type and ID atom of a description contains child atoms, rather than data, it defines a group. A group is a set of related atoms, where the relationship amongst them can be based on attributes such as:

layout--for example, the group is a set of text labels that should be aligned.
spatial--for example, the items in the group should be placed side by side to optimize dialog box layout.
naming--the items in the group are related controls that should be displayed under a single heading in the dialog box.
usage--a pair of long integers may together specify a coordinate. In this case, they can be grouped together and the group's parameter data usage atom set to kParameterUsagePoint .

Groups can be nested within one another as needed. Groups can optionally have a name, which allows your application to place grouped parameters within a panel or tabbed group under that name.

Listing 27 shows an example of a group, which in this case contains a single parameter description.

Listing 27 An example group atom from an 'atms' resource definition.



 
kParameterAtomTypeAndID, 100, noChildren,

{

    OSType { "none" };      // Use 'none' as this is not a real parameter

    long { "0" };

    kAtomNoFlags;

    string { "" };

};



kParameterDataBehavior, 100, noChildren,

{

    kParameterItemGroupDivider; // Use a divider to separate this group

    kGroupNoFlags;

};



kParameterDataType, 100, 1*5,   // 1 parameter * 5 atoms to describe each

                                //parameter

{

};



 


kParameterAtomTypeAndID, 3, noChildren,

{

    OSType { "pMul" };

    long { "1" };

    kAtomNotInterpolated;

    string { "Pre-multiply color" };

};



kParameterDataType, 3, noChildren,

{

    kParameterTypeDataRGBValue;

};



kParameterDataRange, 3, noChildren,

{

    short { "0" };

    short { "0" };

    short { "0" };

    short { "65535" };

    short { "65535" };

    short { "65535" };

};



kParameterDataBehavior, 3, noChildren,

{

    kParameterItemColorPicker;

    long { "0" };

};



kParameterDataDefaultItem, 3, noChildren,

{

    short { "65535" };

    short { "65535" };

    short { "65535" };

};

Enumeration Lists

When an enumerated type is required for a parameter value, a new enumeration list is placed directly into the root atom container. Enumeration lists are arrays of name-and-value pairings in the following format:



 
typedef struct

{

    long    value;

    Str255  name;

} EnumValuePair;



typedef struct

{

    long            enumCount;  // number of enumeration items to follow

    EnumValuePair   values[1];  // values and names for them

} EnumListRecord;

The type of an enumeration list atom is kParameterEnumList ('enum' ). Listing 28 shows an enumeration list that contains three elements.

Listing 28 An example enumeration list from an 'atms' resource definition.



 
kParameterEnumList, 1, noChildren,

{

    long { "3" };           // No of elements in the enum



    long {"1"}; string { "Straight Alpha" };

    long {"2"}; string { "Pre-multiply Alpha" };

    long {"3"}; string { "Reverse Alpha" };

};

Source Count

The source count atom (kParameterSourceCountName , 'srcs' ) contains a single long integer value that defines the maximum number of sources that this effect can accept. The atom is always placed in the root atom container of the parameter description.

The source count atom is required.